%%% Přílohy k diplomové práci, existují-li (různé dodatky jako výpisy programů,
%%% diagramy apod.). Každá příloha musí být alespoň jednou odkazována z vlastního
%%% textu práce. Přílohy se číslují.
\appendix
\chapter{Attachments}

The thesis should be accompanied by a CD with the folowing contents:

\begin{itemize}
  \item README.TXT -- content guide
  \item thesis.pdf -- the text of the master thesis
  \item burglar-game/ -- source codes of the game, together with the documentation and the thesis sources
  \item burglar-game-1.0-SNAPSHOT/ -- the compiled version of the program
  \item planner\_tests/ -- planning systems, test domain, test problems, brief test results
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{User documentation -- game}
\label{chap:userDocGame}

In this section we describe the buttons and methods the player may use to interact with the game.

\section{Running the game}
\label{sec:runningTheGame}

Our program requires a \emph{Java} executing environment; it can be started with the following command:
\begin{verbatim}
run.sh
\end{verbatim}
It has four possible command line parameters:
\begin{description}
  \item [-width $<$number$>$] Sets the screen width in pixels. It can be omitted.
  \item [-height $<$number$>$] Sets the screen height in pixels. It can be omitted.
  \item [-rate] Displays the current frame rate of the program. It can be omitted.
  \item [-replan\_on\_knowledge] Instructs the agents to replan after gathering new knowledge.
  \item [-resources $<$string$>$] Sets the resource folder path, where the program looks for the maps, image resources, sounds, and planning tools. It can be omitted, the default value is ``$./resources/$''.
\end{description}

\section{Adding new levels to the game}

To be found, the level files must be placed into the \emph{map} directory on the \emph{resources} path.

\section{Status line}
\label{sec:statusLine}

The lower left corner contains constantly updating \emph{status line} that provides important additional information about the objects the cursor is idling above. Some of the details displayed here are unfortunately not available in the graphic environment (for example the identifier of a door's key, or the contents of a container).
\newline
\newline

Its format is:

[$<${\bf planning state}$>$, $<${\bf running state}$>$] $|$ [penalties: $<${\bf penalties}$>$] [{\bf x}, {\bf y}] $|$ {\bf objectType}($<${\bf object id}$>$) {\bf [inventory or significant properties], ...}
\newline
\newline
Where
\begin{itemize}
  \item {\bf planning state} indicates whether the gameplay is running or is paused to replan agent behavior.
  \item {\bf running state} indicates whether the game is running or paused by the player.
  \item {\bf penalties} the gathered penalty points on the level.
  \item {\bf [x, y]} are the cursor coordinates on the layout. 
  \item {\bf objectType($<$object id$>$)} the type, and the program-wide unique identifier of the object.
  \item {\bf [inventory or significant properties]} the content of the object's inventory or the relevant details of the object referred to in the {\bf object id}.
\end{itemize}

\section{Buttons and shortcuts}
\label{sec:buttonsAndShortcuts}

The lower right corner of the screen we call \emph{button panel} that contains the following control buttons:

\begin{itemize}
  \item {\bf Inc Distance} -- Increases the length of the visualized section of the currently selected agent's plan. It costs 20 penalty points to use this button.
  \item {\bf Dec Distance} -- Decreases the length of the visualized section of the currently selected agent's plan.
  \item {\bf Speed up} -- Increases the game speed. Its keyboard shortcut is {\bf +}.
  \item {\bf Slow down} -- Decreases the game speed. Its keyboard shortcut is {\bf -}.
  \item {\bf Pause/Continue} -- Pauses or continues the execution of agent plans. Its keyboard shortcut is {\bf \{Space Bar\}}.
  \item {\bf Restart} -- Restores the current level to its starting state.
  \item {\bf Leave} -- Returns the player to the main menu.
  \item {\bf Exit} -- Finishes the whole program. Its keyboard shortcut is {\bf \{Escape\}}.
  \item {\bf \{Direction Keys\}} -- Moves around on the game area.
\end{itemize}

\section{Context menu}
\label{sec:contextMenu}

Clicking on a game tile that contains one or more objects the player can interact with brings up the context menu with the list of available actions.

\begin{itemize}
  \item {\bf Open} -- If the selected position contains a door, or a container, opens it. It costs 100 penalty points to use this button.
  \item {\bf Close} -- If the selected position contains a door, or a container, closes it. It costs 100 penalty points to use this button.
  \item {\bf Lock} -- If the selected position contains a door, or a container, locks it. It costs 100 penalty points to use this button.
  \item {\bf Unlock} -- If the selected position contains a door, or a container, unlocks it. It costs 100 penalty points to use this button.
  \item {\bf Close + Lock} -- If the selected position contains a door, or a container, closes, and locks it. It costs 200 penalty points to use this button.
  \item {\bf Activate} -- If the selected position contains a camera or a vending machine, it gets activated. Activating a camera costs 500 penalty points, while activating a vending machine costs 50.
  \item {\bf Deactivate} -- If the selected position contains a camera, it gets deactivated. It costs 500 penalty points to use this button.
  \item {\bf Show Intent} -- If the selected position contains an agent, visualizes its intent line. It costs 100 penalty points to use this button.
  \item {\bf Hide Intent} -- If the selected position contains an agent, it hides its intent line. It costs 0 penalty points to use this button.
  \item {\bf Daze}  -- If the selected position contains a guard, it gets stunned, and won't recover until the end of the level. It costs 1000 penalty points to use this button.
  \item {\bf Cancel} -- Closes the context menu.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{User documentation -- level generator}
\label{chap:runningTheGenerator}

\section{Running the generator}

It is a purely console application without graphic output; it can be started with a following command:

\begin{verbatim}
run.sh -generator -m <STRING> -l <STRING> -t <NUMBER>
\end{verbatim}

It has four possible command line parameters:
\begin{description}
  \item [-generator] Informs the program that the user wants to run the level generator, not the game itself.
  \item [-m $<$string$>$] Sets the path to the input map file where the starting layout can be found. If no input is defined, tries to receive it from standard input.
  \item [-l $<$string$>$] Sets the path to the output level file where the resulted layout should be written. If no output is defined, sends the result to standard output.
  \item [-t $<$number$>$] Sets the required number of pitfalls to be added.
\end{description}

\section{Usage example}

\begin{verbatim}
run.sh -generator -m input_map.xml -l output_level.xml -t 3
\end{verbatim}

Opens the input\_map.xml file and attempts to add 3 pitfals to the burglar agent's path; finaly puts the resulted map to the output\_level.xml file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Level files}

Technically a layout file and a level file looks the same. The only difference is in the existence of traps. In addition a human developer can easily modify the output of the level generator to add additional player hints, traps, or any other objects.

The levels and maps are stored as XML files in the preset map directory; their exact format is described in the ``map.dtd'' file.

To work correctly these files have to fulfill the following additional requirements:

The world layout must contain at least one room, a single burglar agent, and a treasure as an aim to collect; every other object is optional. There can't be multiple objects with the same unique identifier except for the ones in the real world and their counterparts in the agents' beliefs; while these beliefs can't contain additional game objects that are non-existent in the true layout.

To be found, the level files must be placed into the \emph{map} directory on the \emph{resources} path.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{PDDL domain}

The final unified domain (agent.pddl) used in planning:

\lstset{tabsize=2, basicstyle=\footnotesize, caption=domain file agent.pddl, label=fig:agent.pddl}
\begin{lstlisting}
; agent domain:
; Csaba Toth

(define (domain agent)
	
	
	(:requirements :strips :typing :adl :preferences)
			; for sgplan
	
	
	
	(:types
		t_burglar t_dog t_guard							- t_agent
		t_key t_treasure t_uniform					- t_item
		t_agent t_container									- t_inventory
		t_container t_door									- t_lockable
		t_camera t_container	\
				t_phone t_switch	\
				t_vender t_door		\
				t_floor t_passiveagent					- t_position
		t_room
	)
	
	
	
	(:predicates
		(closed ?position - t_lockable)
				; a lockable position is closed
		(locked ?position - t_lockable)
				; a lockable position is locked
		(needs_key ?lockable - t_lockable ?key - t_key)
				; the key needed to unlock the lockable position
		(agent_near ?agent - t_agent ?position - t_position)
				; the agent stands next to the position
		(agent_in ?agent - t_agent ?room - t_room)
				; the agent is in the room
		(position_in ?position - t_position ?room - t_room)
				; the position is in the room
		(door_connects ?door - t_door ?room1 - t_room ?room2 - t_room)
				; the door connects the two rooms together
		(contains ?inventory - t_inventory ?item - t_item)
				; the container contains the item
		(visited ?agent - t_agent ?room - t_room)
				; the agent has allready visited the room
		(observed ?agent - t_agent)
				; the agent has been observed by a guard or a camera
		(room_observed ?room - t_room)
				; the room is being observed by a guard or a camera
		(position_used ?agent - t_agent ?vender - t_vender)
				; the agent used a vender
	)
	
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; actions:
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;; move			
;;;;		- leaves a position and goes to another
;;;;			one in the same room
;;;;
	(:action move
		:parameters
		(
			?agent	- t_agent
			?start	- t_position
			?aim		- t_position
			?room		- t_room
		)
		:precondition
		(and
			(agent_in ?agent ?room)
			(position_in ?aim ?room)
			(agent_near ?agent ?start)
			(not (agent_near ?agent ?aim))
		)
		:effect
		(and
			(agent_near ?agent ?aim)
			(not (agent_near ?agent ?start))
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;; enter_observed
;;;;		- crosses the door to an observed room
;;;;			without disguise
;;;;
	(:action enter_observed
		:parameters
		(
			?agent			- t_agent
			?door				- t_door
			?room_from	- t_room
			?room_to		- t_room
		)
		:precondition
		(and
			(agent_in ?agent ?room_from)
			(door_connects ?door ?room_from ?room_to)
			(agent_near ?agent ?door)
			(not (closed ?door))
		)
		:effect
		(and
			(agent_in ?agent ?room_to)
			(not (agent_in ?agent ?room_from))
			(visited ?agent ?room_to)
			(visited ?agent ?room_from)
			(observed ?agent)
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;; enter_unobserved
;;;;		- crosses the door to un unobserved
;;;;			room or in disguise
;;;;
	(:action enter_unobserved
		:parameters
		(
			?agent			- t_agent
			?door				- t_door
			?room_from	- t_room
			?room_to		- t_room
			?uniform		- t_uniform
		)
		:precondition
		(and
			(agent_in ?agent ?room_from)
			(door_connects ?door ?room_from ?room_to)
			(agent_near ?agent ?door)
			(not (closed ?door))
			
			(or
				(contains ?agent ?uniform)
				(not (room_observed ?room_to))
			)
		)
		:effect
		(and
			(agent_in ?agent ?room_to)
			(not (agent_in ?agent ?room_from))
			(visited ?agent ?room_to)
			(visited ?agent ?room_from)
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;; open
;;;;		- opens a lockable position
;;;;
	(:action open
		:parameters
		(
			?agent		- t_agent
			?lockable	- t_lockable
		)
		:precondition
		(and
			(agent_near ?agent ?lockable)
			(closed ?lockable)
			(not(locked ?lockable))
		)
		:effect
		(and
			(not (closed ?lockable))
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;








;;;; close
;;;;		- closes a lockable position
;;;;
	(:action close
		:parameters
		(
			?agent		- t_agent
			?lockable	- t_lockable
		)
		:precondition
		(and
			(agent_near ?agent ?lockable)
			(not (closed ?lockable))
		)
		:effect
		(and
			(closed ?lockable)
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;; unlock
;;;;		- unlocks a lockable position
;;;;
	(:action unlock
		:parameters
		(
			?agent		- t_agent
			?lockable	- t_lockable
			?key			- t_key
		)
		:precondition
		(and
			(agent_near ?agent ?lockable)
			(locked ?lockable)
			(contains ?agent ?key)
			(needs_key ?lockable ?key)
		)
		:effect
		(and
			(not (locked ?lockable))
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;















;;;; lock
;;;;		- locks a lockable position
;;;;
	(:action lock
		:parameters
		(
			?agent		- t_agent
			?lockable	- t_lockable
			?key			- t_key
		)
		:precondition
		(and
			(agent_near ?agent ?lockable)
			(not (locked ?lockable))
			(contains ?agent ?key)
			(needs_key ?lockable ?key)
		)
		:effect
		(and
			(locked ?lockable)
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;; pick_up
;;;;		- picks an item from a container
;;;;
	(:action pick_up
		:parameters
		(
			?agent			- t_agent
			?container	- t_container
			?item				- t_item
		)
		:precondition
		(and
			(agent_near ?agent ?container)
			(not (closed ?container))
			(contains ?container ?item)
		)
		:effect
		(and
			(not (contains ?container ?item))
			(contains ?agent ?item)
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;












;;;; take_clothes
;;;;		- takes clothes from a passive agent
;;;;			in the same room
;;;;
	(:action take_clothes
		:parameters
		(
			?agent				- t_agent
			?passiveagent	- t_passiveagent
			?uniform			- t_uniform
		)
		:precondition
		(and
			(agent_near ?agent ?passiveagent)
		)
		:effect
		(and
			(contains ?agent ?uniform)
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;; use
;;;;		- uses a position
;;;;
	(:action use
		:parameters
		(
			?agent	- t_agent
			?vender - t_vender
		)
		:precondition
		(and
			(agent_near ?agent ?vender)
		)
		:effect
		(and
			(position_used ?agent ?vender)
		)
	)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
)
\end{lstlisting}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Levels in planner tests}


\begin{figure}[H]
	\begin{center}
	\includegraphics[width=145mm]{../img/screenshots/planners/test1.eps}
	\end{center}	
	\caption{Level ``complex.xml'' used in planning system test 1 (results listed in table~\ref{tab:test1}) and the solution generated by SGPlan 5.22}
	\label{fig:test1}
\end{figure}

\begin{figure}[H]
	\begin{center}
	\includegraphics[width=145mm]{../img/screenshots/planners/test2.eps}
	\end{center}	
	\caption{Level ``complex.xml'' used in planning system test 2 (results listed in table~\ref{tab:test2}) and the solution generated by SGPlan 5.22}
	\label{fig:test2}
\end{figure}

\begin{figure}[H]
	\begin{center}
	\includegraphics[width=155mm]{../img/screenshots/planners/test3.eps}
	\end{center}	
	\caption{Level ``complex.xml'' used in planning system test 3 where we marked the room to avoid with a red X}
	\label{fig:test3}
\end{figure}

\begin{figure}[H]
	\begin{center}
	\includegraphics[width=145mm]{../img/screenshots/planners/test4.eps}
	\end{center}	
	\caption{Level ``map-chess-board.xml'' used in planning system test 4 (results listed in table~\ref{tab:test4})}
	\label{fig:test4}
\end{figure}


